---
type: integration
title: '@astrojs/mdx'
description: Astro 프로젝트에서 @astrojs/mdx 통합을 사용하는 방법을 알아보세요.
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/'
category: other
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

이 **[Astro 통합][astro-integration]** 을 통해 [MDX](https://mdxjs.com/) 컴포넌트를 사용할 수 있으며 페이지를 `.mdx` 파일로 생성할 수 있습니다.

## 왜 MDX인가?

MDX를 사용하면 Astro에서 [Markdown 콘텐츠 내에서 변수, JSX 표현식 및 컴포넌트를 사용](/ko/guides/markdown-content/#mdx-전용-기능)할 수 있습니다. MDX로 작성된 기존 콘텐츠가 있는 경우 이 통합을 통해 해당 파일을 Astro 프로젝트로 가져올 수 있습니다.

## 설치

Astro에는 공식 통합 설정을 자동화하는 `astro add` 명령이 포함되어 있습니다. 원하는 경우 대신 [통합을 수동으로 설치](#수동-설치)할 수 있습니다.

새 터미널 창에서 다음 명령 중 하나를 실행합니다.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add mdx
  ```
  </Fragment>
 </PackageManagerTabs>

문제가 발생하면 [GitHub에서 언제든지 보고](https://github.com/withastro/astro/issues)하고 아래 수동 설치 단계를 시도해 보세요.

### 수동 설치

먼저 `@astrojs/mdx` 패키지를 설치하세요.

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/mdx
  ```
  </Fragment>
</PackageManagerTabs>

그런 다음 `integrations` 속성을 사용하여 `astro.config.*` 파일에 통합을 적용합니다.

```js title="astro.config.mjs" ins={2} ins="mdx()"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [mdx()],
});
```

### 편집기 통합

[VS Code](https://code.visualstudio.com/)에서 편집기를 지원하려면 [공식 MDX 확장 프로그램](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)을 설치하세요.

다른 편집기의 경우 [MDX 언어 서버](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server)를 사용하세요.

## 사용하기

Astro MDX 통합을 사용하면 `src/pages/` 디렉터리에 `.mdx` 파일을 추가하여 [프로젝트에 MDX 페이지를 추가](/ko/guides/markdown-content/#markdown-및-mdx-페이지)할 수 있습니다. [`.mdx` 파일을 `.astro` 파일로 가져올 수도 있습니다](/ko/guides/markdown-content/#markdown-가져오기).

Astro의 MDX 통합은 Markdown 스타일의 프런트매터를 포함하여 표준 MDX에 기능을 추가합니다. 이를 통해 [특별한 프런트매터 `layout` 속성](/ko/guides/markdown-content/#프런트매터-layout)과 같은 Astro에 내장된 Markdown 기능 대부분을 사용할 수 있습니다.

[Markdown 및 MDX 가이드](/ko/guides/markdown-content/)의 예시를 통해 Astro에서 MDX가 어떻게 작동하는지 알아보세요.

표준 MDX 기능 사용에 대해 알아보려면 [MDX 문서](https://mdxjs.com/docs/what-is-mdx/)를 방문하세요.

## 구성

MDX 통합이 설치되면 Astro 프로젝트에서 `.mdx` 파일을 사용하기 위해 구성할 필요가 없습니다.

다음 옵션을 사용하여 MDX가 렌더링되는 방식을 구성할 수 있습니다.

* [Markdown 구성에서 상속된 옵션](#markdown-구성에서-상속된-옵션)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`optimize`](#optimize)

### Markdown 구성에서 상속된 옵션

모든 [`markdown` 구성 옵션](/ko/reference/configuration-reference/#markdown-옵션)은 MDX 통합에서 별도로 구성할 수 있습니다. 여기에는 remark 및 rehype 플러그인, 구문 강조 등이 포함됩니다. 옵션은 기본적으로 Markdown 구성의 옵션으로 설정됩니다 ([이를 수정하려면 `extendMarkdownConfig` 옵션 참조](#extendmarkdownconfig)).

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});
```

:::caution
MDX는 remark 및 rehype 플러그인을 문자열로 전달하는 것을 지원하지 않습니다. 대신 플러그인 기능을 설치하고 가져와 적용해야 합니다.
:::

<ReadMore>전체 옵션 목록은 [Markdown 옵션 참조](/ko/reference/configuration-reference/#markdown-옵션)를 확인하세요.</ReadMore>

### `extendMarkdownConfig`

* **타입:** `boolean`
* **기본값:** `true`

MDX는 기본적으로 [프로젝트의 기존 Markdown 구성](/ko/reference/configuration-reference/#markdown-옵션)을 확장합니다. 개별 옵션을 재정의하려면 MDX 구성에서 해당 옵션을 지정하면 됩니다.

예를 들어 GitHub 기반 Markdown을 비활성화하고 MDX 파일에 대해 다른 remark 플러그인 세트를 적용해야 한다고 가정해 보겠습니다. 기본적으로 `extendMarkdownConfig`가 활성화된 상태에서 이러한 옵션을 다음과 같이 적용할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // Markdown에서 상속된 `syntaxHighlight`

      // 마크다운 `remarkPlugins`가 무시되었습니다.
      // `remarkPlugin2`만 적용되었습니다.
      remarkPlugins: [remarkPlugin2],
      // `gfm`이 `false`로 재정의되었습니다.
      gfm: false,
    }),
  ],
});
```

MDX에서 `markdown` 구성 확장을 비활성화해야 할 수도 있습니다. 이를 위해 `extendMarkdownConfig`를 `false`로 설정하세요.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // markdown 구성은 이제 무시됩니다.
      extendMarkdownConfig: false,
      // 'remarkPlugins'가 적용되지 않았습니다.
    }),
  ],
});
```

### `recmaPlugins`

출력되는 [estree](https://github.com/estree/estree)를 직접 수정하는 플러그인입니다. 이는 MDX 파일에서 JavaScript 변수를 수정하거나 삽입하는 데 유용합니다.

[AST Explorer를 사용](https://astexplorer.net/)하여 estree 출력을 수행하고 [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/)를 사용하여 JavaScript 노드를 검색하는 것이 좋습니다.

### `optimize`

* **타입:** `boolean | { customComponentNames?: string[] }`

이는 내부 rehype 플러그인을 통해 더 빠른 빌드 및 렌더링을 위해 MDX 출력을 최적화하기 위한 선택적 구성 설정입니다. MDX 파일이 많고 빌드 속도가 느린 경우에 유용할 수 있습니다. 그러나 이 옵션은 일부 이스케이프 처리되지 않은 HTML을 생성할 수 있으므로 활성화한 후에도 사이트의 대화형 부분이 여전히 올바르게 작동하는지 확인하세요.

이는 기본적으로 비활성화되어 있습니다. MDX 최적화를 활성화하려면 MDX 통합 구성에 다음을 추가하십시오.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});
```

#### `customComponentNames`

* **타입:** `string[]`

MDX 최적화 프로그램이 [컴포넌트 prop을 통해 가져온 MDX 콘텐츠로 전달된 사용자 정의 컴포넌트](/ko/guides/markdown-content/#가져온-mdx가-있는-사용자-정의-컴포넌트)를 처리하지 못하도록 방지하는 `optimize`의 선택적 속성입니다.

최적화 프로그램이 콘텐츠를 정적 문자열로 변환하므로 동적으로 렌더링해야 하는 사용자 정의 컴포넌트가 중단되기 때문에 최적화에서 이러한 컴포넌트를 제외해야 합니다.

예를 들어 다음 의도된 MDX 출력은 모두 `"<h1>...</h1>"`이 아닌 `<Heading>...</Heading>`입니다.

```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />
```

`customComponentNames` 속성을 사용하여 이에 대한 최적화를 구성하려면 맞춤 컴포넌트로 처리되어야 하는 HTML 요소 이름의 배열을 지정하세요.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // 최적화 프로그램이 'h1' 요소를 처리하지 못하도록 방지
        // 이는 맞춤 컴포넌트로 처리됩니다.
        customComponentNames: ['h1'],
      },
    }),
  ],
});
```

MDX 파일이 [`export const components = { ... }`를 사용하여 사용자 정의 컴포넌트를 구성](/ko/guides/markdown-content/#html-요소에-맞춤-컴포넌트-할당)하는 경우, 이 옵션을 수동으로 구성할 필요가 없습니다. 최적화 프로그램은 이를 자동으로 감지합니다.

## 예

[Astro MDX 시작 템플릿](https://github.com/withastro/astro/tree/latest/examples/with-mdx)은 Astro 프로젝트에서 MDX 파일을 사용하는 방법을 보여줍니다.

[astro-integration]: /ko/guides/integrations-guide/

[astro-ui-frameworks]: /ko/guides/framework-components/#using-framework-components
